v2.2.2

Compare Source

🧪 Tests

• prevent infinite loop when dragging external items in controlled state (#​2210) - #​2225 by @​STRML

🔧 Internal Changes

• prevent infinite loop when dragging external items in controlled state (#​2210) - #​2225 by @​STRML

v2.2.1

Compare Source

Bug Fixes

• Drag position: Fix items jumping half a screen down when drag starts on a grid container offset from the page top. Removed calcDragPosition from default position strategies since react-draggable handles parent-relative coordinates correctly. #​2223
• Compactor: Ensure all internal v2 code uses compactor.compact() instead of the legacy compact() function. Added optional compactor prop to hooks (useGridLayout, useResponsiveLayout) that takes precedence over compactType/allowOverlap. Fixed negative coordinate handling in compactors. #​2222, fixes #​2213
• Drag-from-outside: Add defensive guards for edge cases with drag enter/leave counter synchronization. Made removeDroppingPlaceholder idempotent and prevented negative counter values. #​2220, fixes #​2210

Internal Changes

• Removed never-exported compat layers (utils-compat.ts, responsive-compat.ts, calculate-compat.ts). These were internal implementation details and were never part of the public API.
• Removed onMove() method from Compactor interface. Custom compactors should implement only compact().

v2.2.0

Compare Source

v2.1.1

Compare Source

Bug Fixes

• Legacy API: Fix allowOverlap not working in legacy mode. Added noOverlapCompactor for when compactType=null and allowOverlap=true. #​2207
• GridLayout: Fix "Maximum update depth exceeded" during drag/resize/drop operations. Used layoutRef pattern to prevent callbacks from being recreated on every layout change. #​2208
• useResponsiveLayout: Fix infinite re-render loop when passing inline objects as layouts prop. Added separate ref to track props vs state changes. #​2209

v2.1.0

Compare Source

New Features

Pluggable Layout Constraints System

A new constraints system allows custom validation and transformation of layout items during drag and resize operations. #​2190

import { createConstraintEnforcer, aspectRatioConstraint, positionConstraint } from "react-grid-layout/core";

const enforcer = createConstraintEnforcer([
  aspectRatioConstraint(16 / 9),
  positionConstraint({ minX: 0, maxX: 10 })
]);

<GridLayout constraintEnforcer={enforcer} />

Fast Compactors for Large Layouts

New O(n log n) compactors in react-grid-layout/extras for layouts with 200+ items:

• fastVerticalCompactor - Up to 45x faster than standard vertical compaction. #​2184
• fastHorizontalCompactor - Up to 74x faster than standard horizontal compaction. #​2189, #​2193

import { fastVerticalCompactor, fastHorizontalCompactor } from "react-grid-layout/extras";

<GridLayout compactor={fastVerticalCompactor} />

Wrap Compactor

New wrapCompactor for paragraph-style layouts where items flow left-to-right and wrap to the next row. #​2186

import { wrapCompactor } from "react-grid-layout/extras";

<GridLayout compactor={wrapCompactor} />

Improved Examples

• Added navigable sidebar to examples for easier exploration
• New grid matrix panel for visualizing layout state. #​2197

Bug Fixes

• WidthProvider: Re-observe element after measureBeforeMount switches from placeholder. #​2198
• Drop positioning: Center dropped items on cursor position instead of top-left corner. #​2196
• Margin calculation: Ensure consistent margins between grid items. #​2195
• Compaction: Disable early break optimization when static items are present, fixing incorrect layouts. #​2194
• Responsive layouts: Prevent infinite layout oscillation in toolbox pattern. #​2192
• CSS: Remove user-select: none from grid items to restore auto-scroll behavior. #​2188

Tests

• Added maxRows enforcement tests for calcXY and calcWH. #​2185

Internal Changes

• Improved changelog action for better automated release notes. #​2199

v2.0.0

Compare Source

Version 2 is a complete TypeScript rewrite with a modernized hooks-based API. See the RFC for the full design document.

Highlights

• Full TypeScript support - First-class types, no more @types/react-grid-layout needed
• React Hooks API - New useContainerWidth, useGridLayout, and useResponsiveLayout hooks
• Composable Configuration - Group related props into focused interfaces (gridConfig, dragConfig, resizeConfig, positionStrategy, compactor)
• Modular Architecture - Tree-shakeable ESM and CJS builds with multiple entry points
• Legacy Compatibility - 100% backwards compatible via react-grid-layout/legacy

Breaking Changes

See the migration section in the README for detailed examples.

width Prop Required

The grid no longer auto-measures width. Use the new useContainerWidth hook:

import ReactGridLayout, { useContainerWidth } from "react-grid-layout";

function MyGrid() {
  const { width, containerRef, mounted } = useContainerWidth();
  return (
    <div ref={containerRef}>
      {mounted && <ReactGridLayout width={width} ... />}
    </div>
  );
}

Or use the legacy wrapper for backwards compatibility:

import ReactGridLayout, { WidthProvider } from "react-grid-layout/legacy";
const GridLayoutWithWidth = WidthProvider(ReactGridLayout);

onDragStart Threshold

onDragStart now fires after 3px of mouse movement, not on mousedown. This fixes #​1341 and #​1401. Use onMouseDown directly on grid items if you need immediate response.

Immutable Callback Parameters

Callback parameters (layoutItem, placeholder) are now read-only. Mutating them in onResize/onDrag callbacks no longer works. Use onLayoutChange or item constraints (minW, maxW, etc.) instead.

data-grid Prop in Legacy Only

The v2 API requires explicit layout prop. The data-grid pattern is only available via the legacy wrapper (react-grid-layout/legacy).

Pluggable Compaction Algorithms

Compaction is now pluggable via the Compactor interface. The default compaction algorithm remains the same as v1 for backwards compatibility. For large layouts (200+ items), an optional O(n log n) fast compactor is available in react-grid-layout/extras:

import { fastVerticalCompactor } from 'react-grid-layout/extras';
<GridLayout compactor={fastVerticalCompactor} />

Other Breaking Changes

• UMD bundle removed - Use a bundler (Vite, webpack, esbuild)
• verticalCompact prop removed - Use compactType={null} or compactor={noCompactor}
• React 18+ required - React 16/17 support is available only via the legacy wrapper

New Features

Entry Points

// v2 API (recommended)
import ReactGridLayout, {
  Responsive,
  useContainerWidth
} from "react-grid-layout";

// Core utilities (framework-agnostic, no React)
import { compact, moveElement, collides } from "react-grid-layout/core";

// Legacy v1 API (100% backwards compatible)
import ReactGridLayout, {
  WidthProvider,
  Responsive
} from "react-grid-layout/legacy";

// Optional extras
import { GridBackground } from "react-grid-layout/extras";

Hooks

• useContainerWidth() - Reactive container width measurement with ResizeObserver
• useGridLayout() - Core layout state management for custom implementations
• useResponsiveLayout() - Responsive breakpoint management

Composable Configuration Interfaces

<ReactGridLayout
  width={width}
  layout={layout}
  gridConfig={{ cols: 12, rowHeight: 30, margin: [10, 10] }}
  dragConfig={{ enabled: true, handle: ".handle", bounded: true }}
  resizeConfig={{ enabled: true, handles: ["se", "sw"] }}
  positionStrategy={transformStrategy}
  compactor={verticalCompactor}
/>

Pluggable Compactors

Create custom compaction algorithms by implementing the Compactor interface:

import {
  verticalCompactor,
  horizontalCompactor,
  noCompactor
} from "react-grid-layout/core";

// Or create custom compactors
const myCompactor: Compactor = {
  type: "custom",
  allowOverlap: false,
  compact(layout, cols) {
    /* ... */
  },
  onMove(layout, item, x, y, cols) {
    /* ... */
  }
};

Position Strategies

Control CSS positioning with the PositionStrategy interface:

import { transformStrategy, absoluteStrategy, createScaledStrategy } from "react-grid-layout/core";

// For scaled containers
<div style={{ transform: "scale(0.5)" }}>
  <ReactGridLayout positionStrategy={createScaledStrategy(0.5)} />
</div>

GridBackground Component

New optional component to visualize the grid structure:

import { GridBackground } from "react-grid-layout/extras";

<GridBackground
  width={width}
  cols={12}
  rowHeight={30}
  rows={10}
  color="#f0f0f0"
/>;

Core Utilities

New calcGridCellDimensions utility for building custom grid overlays:

import { calcGridCellDimensions } from "react-grid-layout/core";

const dims = calcGridCellDimensions({
  width: 1200,
  cols: 12,
  rowHeight: 30,
  margin: [10, 10]
});
// { cellWidth, cellHeight, offsetX, offsetY, gapX, gapY, cols, containerWidth }

React 18 Compatibility

• Full React 18 support. The library now works seamlessly with React 18's automatic batching without any flushSync warnings.
• Removed flushSync usage from drag and resize handlers.

Bugfixes

• Fixed operator precedence bug in moveDroppingItem where shouldDrag would incorrectly evaluate to true when only the top position changed.
• Fixed resize position calculation when node is falsy in onResizeHandler.

Internal Changes

• Complete TypeScript rewrite - All code is now TypeScript with full type coverage
• Migrated from Flow to TypeScript - Removed all Flow annotations
• Modular package structure - src/core/ (pure TS), src/react/ (React bindings), src/legacy/ (v1 compatibility)
• Build system - Now uses tsup for ESM, CJS, and declaration file generation
• Migrated test suite from Enzyme to React Testing Library
• ESLint 9 with flat config
• Removed lib/ folder and Flow configuration
• Removed snapshot tests in favor of behavioral tests

Migration Guide

Quick migration (no code changes):

- import GridLayout from 'react-grid-layout';
+ import GridLayout from 'react-grid-layout/legacy';

Full migration (recommended for new features):

1. Replace WidthProvider HOC with useContainerWidth hook
2. Replace data-grid props with explicit layout prop
3. Use configuration interfaces (gridConfig, dragConfig, etc.) for cleaner props
4. Update any code that mutates callback parameters to use onLayoutChange instead

See the README for detailed examples